<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Loop (parse a string)</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Loop (parse a string)</h1>

<p>Retrieves substrings (fields) from a string, one at a time.</p>

<pre class="Syntax">Loop, Parse, InputVar [, Delimiters, OmitChars]</pre>
<h3>Parameters</h3>
<dl>

  <dt>Parse</dt>
  <dd><p>This parameter must be the word PARSE, and unlike other loop types, it must not be a variable reference that resolves to the word PARSE.</p></dd>

  <dt>InputVar</dt>
  <dd>
    <p>The name of the variable whose contents will be analyzed. Do not enclose the name in percent signs unless you want the <em>contents</em> of the variable to be used as the name.</p>
    <p><span class="ver">[v1.1.21+]:</span> This parameter can be an <code>% <a href="../Variables.htm#Expressions">expression</a></code>, but the percent-space prefix must be used.</p>
  </dd>

  <dt>Delimiters</dt>
  <dd><p>If this parameter is blank or omitted, each character of <em>InputVar</em> will be treated as a separate substring.</p>
      <p>If this parameter is <strong>CSV</strong>, <em>InputVar</em> will be parsed in standard comma separated value format. Here is an example of a CSV line produced by MS Excel:</p>
<pre>&quot;first field&quot;,SecondField,&quot;the word &quot;&quot;special&quot;&quot; is quoted literally&quot;,,&quot;last field, has literal comma&quot;</pre>
      <p>Otherwise, <em>Delimiters</em> contains one or more  characters (case sensitive), each of which is used to determine where the boundaries between substrings occur in <em>InputVar</em>.</p>
      <p>Delimiter characters are not considered to be part of the substrings themselves. In addition, if there is nothing between a pair of delimiters within <em>InputVar</em>, the corresponding substring will be empty.</p>
      <p>For example: <code>`,</code> (an escaped comma) would divide the string based on every occurrence of a comma. Similarly, %A_Tab%%A_Space% would start a new substring every time a space or tab is encountered in <em>InputVar</em>.</p>
      <p>To use a string as a delimiter rather than a character, first use <a href="StringReplace.htm">StringReplace</a> to replace all occurrences of the string with a single character that is never used literally in the text, e.g. one of these special characters: &cent;&curren;&yen;&brvbar;&sect;&copy;&ordf;&laquo;&reg;&micro;&para;. Consider this example, which uses the string &lt;br&gt; as a delimiter:</p>
      <pre>StringReplace, NewHTML, HTMLString, &lt;br&gt;, &cent;, All
Loop, parse, NewHTML, &cent; <em>; Parse the string based on the cent symbol.</em>
{
...
}</pre></dd>

  <dt>OmitChars</dt>
  <dd><p>An optional list of characters (case sensitive) to exclude from the beginning and end of each substring. For example, if <em>OmitChars</em> is %A_Space%%A_Tab%, spaces and tabs will be removed from the beginning and end (but not the middle) of every retrieved substring.</p>
    <p>If <em>Delimiters</em> is blank, <em>OmitChars</em> indicates which characters should be excluded from consideration (the loop will not see them).</p>
    <p>Unlike the last parameter of most other commands, commas in <em>OmitChars</em> must be escaped (`,).</p></dd>

</dl>

<h3>Remarks</h3>
<p>A string parsing loop is useful when you want to operate on each field contained in a string, one at a time. Parsing loops use less memory than <a href="StringSplit.htm">StringSplit</a> (since StringSplit creates a permanent <a href="../misc/Arrays.htm#pseudo">pseudo-array</a>) and in most cases they are easier to use.</p>
<p><a name="LoopField"></a>The built-in variable <strong>A_LoopField</strong> exists within any parsing loop. It contains the contents of the current substring (field) from <em>InputVar</em>. If an inner parsing loop is enclosed by an outer parsing loop, the innermost loop's field will take precedence.</p>
<p>Although there is no built-in variable &quot;A_LoopDelimiter&quot;, the example at the very bottom of this page demonstrates how to detect which delimiter was encountered for each field.</p>
<p>There is no restriction on the size of <em>InputVar</em> or its fields. In addition, if <em>InputVar</em>'s contents change during the execution of the loop, the loop will not &quot;see&quot; the changes because it is operating on a temporary copy of the original contents.</p>
<p>To arrange the fields in a different order prior to parsing, use the <a href="Sort.htm">Sort</a> command.</p>
<p>See <a href="Loop.htm">Loop</a> for information about <a href="Block.htm">Blocks</a>, <a href="Break.htm">Break</a>, <a href="Continue.htm">Continue</a>, and the A_Index variable (which exists in every type of loop).</p>
<h3>Related</h3>
<p><a href="StringSplit.htm">StringSplit</a>, <a href="LoopReadFile.htm">file-reading loop</a>, <a href="Loop.htm">Loop</a>, <a href="Break.htm">Break</a>, <a href="Continue.htm">Continue</a>, <a href="Block.htm">Blocks</a>, <a href="Sort.htm">Sort</a>, <a href="FileSetAttrib.htm">FileSetAttrib</a>, <a href="FileSetTime.htm">FileSetTime</a></p>
<h3>Examples</h3>
<pre class="NoIndent"><em>; Example #1:</em>
Colors = red,green,blue
Loop, parse, Colors, `,
{
    MsgBox, Color number %A_Index% is %A_LoopField%.
}</pre>
<p>&nbsp;</p>
<pre class="NoIndent"><em>; Example #2: Read the lines inside a variable, one by one (similar to a <a href="LoopReadFile.htm">file-reading</a> loop).
; A file can be loaded into a variable via <a href="FileRead.htm">FileRead</a>:</em>
Loop, parse, FileContents, `n, `r  <em>; Specifying `n prior to `r allows both Windows and Unix files to be parsed.</em>
{
    MsgBox, 4, , Line number %A_Index% is %A_LoopField%.`n`nContinue?
    IfMsgBox, No, break
}</pre>
<p>&nbsp;</p>
<pre class="NoIndent"><em>; Example #3: This is the same as the example above except that it's for the clipboard.
; It's useful whenever the clipboard contains files, such as those copied from an open
; Explorer window (the program automatically converts such files to their file names):</em>
Loop, parse, clipboard, `n, `r
{
    MsgBox, 4, , File number %A_Index% is %A_LoopField%.`n`nContinue?
    IfMsgBox, No, break
}</pre>
<p>&nbsp;</p>
<pre class="NoIndent"><em>; Example #4: Parse a comma separated value (CSV) file:</em>
Loop, read, C:\Database Export.csv
{
    LineNumber = %A_Index%
    Loop, parse, A_LoopReadLine, CSV
    {
        MsgBox, 4, , Field %LineNumber%-%A_Index% is:`n%A_LoopField%`n`nContinue?
        IfMsgBox, No
            return
    }
}</pre>
<p>&nbsp;</p>
<pre class="NoIndent"><em>; Example #5: Determining which delimiter was encountered.</em>

<em>; Initialize string to search.</em>
Colors = red,green|blue;yellow|cyan,magenta
<em>; Initialize counter to keep track of our position in the string.</em>
Position := 0

Loop, Parse, Colors, `,|;
{
    <em>; Calculate the position of the delimiter at the end of this field.</em>
    Position += StrLen(A_LoopField) + 1
    <em>; Retrieve the delimiter found by the parsing loop.</em>
    Delimiter := SubStr(Colors, Position, 1)

    MsgBox Field: %A_LoopField%`nDelimiter: %Delimiter%
}</pre>

</body>
</html>
